home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kiconloader.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  18.8 KB  |  554 lines
  1. /* vi: ts=8 sts=4 sw=4
  2.  *
  3.  * This file is part of the KDE project, module kdecore.
  4.  * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
  5.  *                    Antonio Larrosa <larrosa@kde.org>
  6.  *
  7.  * This is free software; it comes under the GNU Library General
  8.  * Public License, version 2. See the file "COPYING.LIB" for the
  9.  * exact licensing terms.
  10.  */
  11.  
  12. #ifndef __KIconLoader_h_Included__
  13. #define __KIconLoader_h_Included__
  14.  
  15. #include <qstring.h>
  16. #include <qpixmap.h>
  17. #include <qiconset.h>
  18.  
  19. // Grmbl, X headers.....
  20. #ifdef Status
  21. #define KIconLoaderXStatus Status
  22. #undef Status
  23. #endif
  24. #include <qmovie.h>
  25. #ifdef KIconLoaderXStatus
  26. #define Status int
  27. #undef KIconLoaderXStatus
  28. #endif
  29.  
  30. #include <kglobal.h>
  31. #include <kinstance.h>
  32. #include <kicontheme.h>
  33.  
  34. struct KIconGroup;
  35. class KIconThemeNode;
  36. class KConfig;
  37. struct KIconLoaderPrivate;
  38. class KStandardDirs;
  39. class KIconEffect;
  40.  
  41.  
  42. /**
  43.  * Iconloader for KDE.
  44.  *
  45.  * KIconLoader will load the current icon theme and all its base themes.
  46.  * Icons will be searched in any of these themes. Additionally, it caches
  47.  * icons and applies effects according the the user's preferences.
  48.  *
  49.  * In KDE, it is encouraged to load icons by "Group". An icon group is a
  50.  * location on the screen where icons are being used. Standard groups are:
  51.  * Desktop, Toolbar, MainToolbar, Small and Panel. Each group has some
  52.  * centrally configured properties bound to it, including the icon size
  53.  * and effects. This makes it possible to offer a consistent icon look in
  54.  * all KDE applications.
  55.  *
  56.  * The standard groups are defined below.
  57.  *
  58.  * @li KIcon::Desktop: Icons in the iconview of konqueror, kdesktop and similar apps.
  59.  * @li KIcon::Toolbar: Icons in toolbars.
  60.  * @li KIcon::MainToolbar: Icons in the main toolbars.
  61.  * @li KIcon::Small: Various small (typical 16x16) places: titlebars, listviews
  62.  * and menu entries.
  63.  * @li KIcon::Panel: Icons in kicker's panel
  64.  *
  65.  * The icons are stored on disk in an icon theme or in a standalone
  66.  * directory. The icon theme directories contain multiple sizes and/or
  67.  * depths for the same icon. The iconloader will load the correct one based
  68.  * on the icon group and the current theme. Icon themes are stored globally
  69.  * in share/icons, or, application specific in share/apps/$appdir/icons.
  70.  *
  71.  * The standalone directories contain just one version of an icon. The
  72.  * directories that are searched are: $appdir/pics and $appdir/toolbar.
  73.  * Icons in these directories can be loaded by using the special group
  74.  * "User".
  75.  *
  76.  */
  77. class KDECORE_EXPORT KIconLoader
  78. {
  79. public:
  80.  
  81.     /**
  82.      * Constructs an iconloader.
  83.      * @param appname Add the data directories of this application to the
  84.      * icon search path for the "User" group. The default argument adds the
  85.      * directories of the current application.
  86.      * @param dirs the KStandardDirs object to use. If null the global one is used
  87.      *
  88.      * Usually, you use the default iconloader, which can be accessed via
  89.      * KGlobal::iconLoader(), so you hardly ever have to create an
  90.      * iconloader object yourself. That one is the current KInstance's
  91.      * (typically KApplication's) iconloader.
  92.      * @see KGlobal::iconLoader()
  93.      * @see KInstance::iconLoader()
  94.      */
  95.     KIconLoader(const QString& appname=QString::null, KStandardDirs *dirs = 0);
  96.  
  97.     /**
  98.      * Cleanup
  99.      */
  100.     ~KIconLoader();
  101.  
  102.     /**
  103.      * Adds @p appname to the list of application specific directories.
  104.      * @param appname The application name.
  105.      */
  106.     void addAppDir(const QString& appname);
  107.  
  108.     /**
  109.      * Loads an icon. It will try very hard to find an icon which is
  110.      * suitable. If no exact match is found, a close match is searched.
  111.      * If neither an exact nor a close match is found, a null pixmap or
  112.      * the "unknown" pixmap is returned, depending on the value of the
  113.      * @p canReturnNull parameter.
  114.      *
  115.      * @param name The name of the icon, without extension.
  116.      * @param group The icon group. This will specify the size of and effects to
  117.      * be applied to the icon.
  118.      * @param size If nonzero, this overrides the size specified by @p group.
  119.      *             See KIcon::StdSizes.
  120.      * @param state The icon state: @p DefaultState, @p ActiveState or
  121.      * @p DisabledState. Depending on the user's preferences, the iconloader
  122.      * may apply a visual effect to hint about its state.
  123.      * @param path_store If not null, the path of the icon is stored here.
  124.      * @param canReturnNull Can return a null pixmap? If false, the
  125.      * "unknown" pixmap is returned when no appropriate icon has been found.
  126.      * @return the QPixmap. Can be null when not found, depending on
  127.      *         @p canReturnNull.
  128.      */
  129.     QPixmap loadIcon(const QString& name, KIcon::Group group, int size=0,
  130.              int state=KIcon::DefaultState, QString *path_store=0L,
  131.              bool canReturnNull=false) const;
  132.  
  133.     /**
  134.      * Creates an icon set, that will do on-demand loading of the icon.
  135.      * Loading itself is done by calling loadIcon .
  136.      *
  137.      * @param name The name of the icon, without extension.
  138.      * @param group The icon group. This will specify the size of and effects to
  139.      * be applied to the icon.
  140.      * @param size If nonzero, this overrides the size specified by @p group.
  141.      *             See KIcon::StdSizes.
  142.      * @param canReturnNull Can return a null iconset? If false, iconset
  143.      * containing the "unknown" pixmap is returned when no appropriate icon has
  144.      * been found.
  145.      * @param immediateExistenceCheck If true on-demand icon loading will be
  146.      * disabled for canReturnNull and a null iconset may be returned immediately
  147.      * @return the icon set. Can be null when not found, depending on
  148.      *          @p canReturnNull.
  149.      * @since 3.5
  150.      */
  151.     QIconSet loadIconSet(const QString& name, KIcon::Group group, int size,
  152.                          bool canReturnNull, bool immediateExistenceCheck);
  153.  
  154.     // KDE4 merge as (const QString&,KIcon::Group,int=0,bool=false,bool=true);
  155.     /**
  156.      * Creates an icon set, that will do on-demand loading of the icon.
  157.      * Loading itself is done by calling loadIcon .
  158.      *
  159.      * @param name The name of the icon, without extension.
  160.      * @param group The icon group. This will specify the size of and effects to
  161.      * be applied to the icon.
  162.      * @param size If nonzero, this overrides the size specified by @p group.
  163.      *             See KIcon::StdSizes.
  164.      * @param canReturnNull Can return a null iconset? If false, iconset
  165.      * containing the "unknown" pixmap is returned when no appropriate icon has
  166.      * been found.
  167.      * @return the icon set. Can be null when not found, depending on
  168.      *          @p canReturnNull.
  169.      * @since 3.1
  170.      */
  171.     QIconSet loadIconSet(const QString& name, KIcon::Group group, int size,
  172.                          bool canReturnNull);
  173.  
  174.     // KDE4 merge as (const QString&,KIcon::Group,int=0,bool=false,bool=true);
  175.     /**
  176.      * Creates an icon set, that will do on-demand loading of the icon.
  177.      * Loading itself is done by calling loadIcon .
  178.      *
  179.      * @param name The name of the icon, without extension.
  180.      * @param group The icon group. This will specify the size of and effects to
  181.      * be applied to the icon.
  182.      * @param size If nonzero, this overrides the size specified by @p group.
  183.      *             See KIcon::StdSizes.
  184.      * @return the icon set. Can be null when not found
  185.      */
  186.     QIconSet loadIconSet(const QString& name, KIcon::Group group, int size=0);
  187.  
  188.     /**
  189.      * Returns the path of an icon.
  190.      * @param name The name of the icon, without extension. If an absolute
  191.      * path is supplied for this parameter, iconPath will return it
  192.      * directly.
  193.      * @param group_or_size If positive, search icons whose size is
  194.      * specified by the icon group @p group_or_size. If negative, search
  195.      * icons whose size is - @p group_or_size.
  196.      *             See KIcon::Group and KIcon::StdSizes
  197.      * @param canReturnNull Can return a null string? If not, a path to the
  198.      *                      "unknown" icon will be returned.
  199.      * @return the path of an icon, can be null or the "unknown" icon when
  200.      *         not found, depending on @p canReturnNull.
  201.      */
  202.     QString iconPath(const QString& name, int group_or_size,
  203.              bool canReturnNull=false) const;
  204.  
  205.     /**
  206.      * Loads an animated icon.
  207.      * @param name The name of the icon.
  208.      * @param group The icon group. See loadIcon().
  209.      * @param size Override the default size for @p group.
  210.      *             See KIcon::StdSizes.
  211.      * @return A QMovie object. Can be null if not found.
  212.      */
  213.     QMovie loadMovie(const QString& name, KIcon::Group group, int size=0) const;
  214.  
  215.     /**
  216.      * Returns the path to an animated icon.
  217.      * @param name The name of the icon.
  218.      * @param group The icon group. See loadIcon().
  219.      * @param size Override the default size for @p group.
  220.      *             See KIcon::StdSizes.
  221.      * @return the full path to the movie, ready to be passed to QMovie's constructor.
  222.      * Empty string if not found.
  223.      */
  224.     QString moviePath(const QString& name, KIcon::Group group, int size=0) const;
  225.  
  226.     /**
  227.      * Loads an animated icon as a series of still frames. If you want to load
  228.      * a .mng animation as QMovie instead, please use loadMovie() instead.
  229.      * @param name The name of the icon.
  230.      * @param group The icon group. See loadIcon().
  231.      * @param size Override the default size for @p group.
  232.      *             See KIcon::StdSizes.
  233.      * @return A QStringList containing the absolute path of all the frames
  234.      * making up the animation.
  235.      */
  236.     QStringList loadAnimated(const QString& name, KIcon::Group group, int size=0) const;
  237.  
  238.     /**
  239.      * Queries all available icons for a specific group, having a specific
  240.      * context.
  241.      * @param group_or_size If positive, search icons whose size is
  242.      * specified by the icon group @p group_or_size. If negative, search
  243.      * icons whose size is - @p group_or_size.
  244.      *             See KIcon::Group and KIcon::StdSizes
  245.      * @param context The icon context.
  246.      * @return a list of all icons
  247.      */
  248.     QStringList queryIcons(int group_or_size, KIcon::Context context=KIcon::Any) const;
  249.  
  250.     /**
  251.      * Queries all available icons for a specific context.
  252.      * @param group_or_size The icon preferred group or size. If available
  253.      * at this group or size, those icons will be returned, in other case,
  254.      * icons of undefined size will be returned. Positive numbers are groups,
  255.      * negative numbers are negated sizes. See KIcon::Group and
  256.      * KIcon::StdSizes
  257.      * @param context The icon context.
  258.      * @return A QStringList containing the icon names
  259.      * available for that context
  260.      */
  261.     QStringList queryIconsByContext(int group_or_size,
  262.                     KIcon::Context context=KIcon::Any) const;
  263.  
  264.     /**
  265.      * @internal
  266.      */
  267.     bool hasContext( KIcon::Context context ) const;
  268.  
  269.     /**
  270.      * Returns a list of all icons (*.png or *.xpm extension) in the
  271.      * given directory.
  272.      * @param iconsDir the directory to search in
  273.      * @return A QStringList containing the icon paths
  274.      * @since 3.1
  275.      */
  276.     QStringList queryIconsByDir( const QString& iconsDir ) const;
  277.  
  278.     /**
  279.      * Returns the current size of the group.
  280.      * @param group the group to check.
  281.      * @return the current size for an icon group.
  282.      */
  283.     int currentSize(KIcon::Group group) const;
  284.  
  285.     /**
  286.      * Returns a pointer to the current theme. Can be used to query
  287.      * available and default sizes for groups.
  288.      * @return a pointer to the current theme. 0 if no theme set.
  289.      */
  290.     KIconTheme *theme() const;
  291.  
  292.     /**
  293.      * Returns a pointer to the KIconEffect object used by the icon loader.
  294.      * @return the KIconEffect.
  295.      */
  296.     KIconEffect *iconEffect() const;
  297.  
  298.     /**
  299.      * Called by KInstance::newIconLoader to reconfigure the icon loader.
  300.      * @param _appname the new application name
  301.      * @param _dirs the new standard directories. If 0, the directories
  302.      *              from KGlobal will be taken.
  303.      */
  304.     void reconfigure( const QString& _appname, KStandardDirs *_dirs );
  305.  
  306.     /**
  307.      * Returns the unknown icon. An icon that is used when no other icon
  308.      * can be found.
  309.      * @return the unknown pixmap
  310.      */
  311.     static QPixmap unknown();
  312.  
  313.     /**
  314.      * Checks whether the user wants to blend the icons with the background
  315.      *  using the alpha channel information for a given group.
  316.      * @param group the group to check
  317.      * @return true if alpha blending is desired
  318.      * @obsolete
  319.      */
  320.     bool alphaBlending( KIcon::Group group ) const;
  321.  
  322.     /**
  323.      * Adds all the default themes from other desktops at the end of
  324.      * the list of icon themes.
  325.      * @since 3.1
  326.      */
  327.     void addExtraDesktopThemes();
  328.  
  329.     /**
  330.      * Returns if the default icon themes of other desktops have been added
  331.      * to the list of icon themes where icons are searched.
  332.      * @since 3.1
  333.      */
  334.     bool extraDesktopThemesAdded() const;
  335.  
  336.     /**
  337.      * Enables on-demand icon loading for QIconSets using QIconFactory.
  338.      * Icons loaded via loadIconSet() will be loaded as soon as they
  339.      * need to be displayed, not earlier.
  340.      *
  341.      * Note that enabling or disabling this only affects loadIconSet()
  342.      * calls after this setting is changed.
  343.      *
  344.      * The default is disabled, as the iconloader object must not be
  345.      * destroyed before all those iconsets are destroyed.
  346.      *
  347.      * (Some broken applications use temporary KIconLoader objects).
  348.      * Every KInstance 's iconloader has this feature enabled.
  349.      *
  350.      * @param enable true to enable delayed icon loading, false to disable
  351.      * @see isDelayedIconSetLoadingEnabled()
  352.      * @see QIconFactory
  353.      * @since 3.1
  354.      */
  355.     void enableDelayedIconSetLoading( bool enable );
  356.  
  357.     /**
  358.      * Checks whether delayed loading for QIconSet is enabled.
  359.      * @return whether icons for QIconSets will be loaded on demand.
  360.      * @see enableDelayedIconSetLoading()
  361.      * @see QIconFactory
  362.      * @since 3.1
  363.      */
  364.     bool isDelayedIconSetLoadingEnabled() const;
  365.  
  366.  
  367.  private:
  368.     /**
  369.      * @internal
  370.      */
  371.     void init( const QString& _appname, KStandardDirs *_dirs );
  372.  
  373.     /**
  374.      * @internal
  375.      * tries to find an icon with the name. It tries some extension and
  376.      * match strategies
  377.      */
  378.     KIcon findMatchingIcon(const QString& name, int size) const;
  379.  
  380.     /**
  381.      * @internal
  382.      * Loads and caches an overlay.
  383.      */
  384.      QImage *loadOverlay(const QString& name, int size) const;
  385.  
  386.     /**
  387.      * @internal
  388.      * Adds themes installed in the application's directory.
  389.      **/
  390.     void addAppThemes(const QString& appname);
  391.  
  392.     /**
  393.      * Adds all themes that are part of this node and the themes
  394.      * below (the fallbacks of the theme) in the tree.
  395.      * @internal
  396.      */
  397.     void addBaseThemes(KIconThemeNode *node, const QString &appname);
  398.  
  399.     /**
  400.      * @internal
  401.      * return the path for the unknown icon in that size
  402.      * @since 3.1
  403.      */
  404.     QString unknownIconPath( int size ) const;
  405.  
  406.     /**
  407.      * Checks if name ends in one of the supported icon formats (i.e. .png)
  408.      * and returns the name without the extension if it does.
  409.      *
  410.      * Otherwise name is returned unchanged.
  411.      *
  412.      * Currently supported:
  413.      *   - png
  414.      *   - xpm
  415.      *   - svg  (if libart is being used)
  416.      *   - svgz (if libart is being used)
  417.      *
  418.      * TODO: KDE 4 make public & static
  419.      * @since 3.1
  420.      */
  421.     QString removeIconExtension(const QString &name) const;
  422.  
  423.     /**
  424.      * Same as removeIconExtension except it prints a debug message
  425.      * if an extension is removed to help catch programming errors.
  426.      *
  427.      * @see findMatchingIcon()
  428.      * @see iconPath()
  429.      *
  430.      * TODO: KDE 4 make static
  431.      */
  432.     QString removeIconExtensionInternal(const QString &name) const;
  433.  
  434.     /**
  435.      * Loads all the different sizes for an iconset.
  436.      */
  437.     QIconSet loadIconSetNonDelayed( const QString& name, KIcon::Group group,
  438.                                     int size, bool canReturnNull );
  439.  
  440.     // @internal the data object
  441.     KIconLoaderPrivate *d;
  442. };
  443.  
  444. /**
  445.  * \relates KIconLoader
  446.  * Load a desktop icon.
  447.  */
  448. KDECORE_EXPORT QPixmap DesktopIcon(const QString& name, int size=0,
  449.             int state=KIcon::DefaultState,
  450.             KInstance *instance=KGlobal::instance());
  451.  
  452. /**
  453.  * \relates KIconLoader
  454.  * Load a desktop icon.
  455.  */
  456. KDECORE_EXPORT QPixmap DesktopIcon(const QString& name, KInstance *instance);
  457.  
  458. /**
  459.  * \relates KIconLoader
  460.  * Load a desktop icon, and apply the necessary effects to get an IconSet.
  461.  */
  462. KDECORE_EXPORT QIconSet DesktopIconSet(const QString& name, int size=0,
  463.             KInstance *instance=KGlobal::instance());
  464.  
  465. /**
  466.  * \relates KIconLoader
  467.  * Load a toolbar icon.
  468.  */
  469. KDECORE_EXPORT QPixmap BarIcon(const QString& name, int size=0, int state=KIcon::DefaultState,
  470.     KInstance *instance=KGlobal::instance());
  471.  
  472. /**
  473.  * \relates KIconLoader
  474.  * Load a toolbar icon.
  475.  */
  476. KDECORE_EXPORT QPixmap BarIcon(const QString& name, KInstance *instance);
  477.  
  478. /**
  479.  * \relates KIconLoader
  480.  * Load a toolbar icon, and apply the necessary effects to get an IconSet.
  481.  */
  482. KDECORE_EXPORT QIconSet BarIconSet(const QString& name, int size=0,
  483.             KInstance *instance=KGlobal::instance());
  484.  
  485. /**
  486.  * \relates KIconLoader
  487.  * Load a small icon.
  488.  */
  489. KDECORE_EXPORT QPixmap SmallIcon(const QString& name, int size=0,
  490.           int state=KIcon::DefaultState,
  491.           KInstance *instance=KGlobal::instance());
  492.  
  493. /**
  494.  * \relates KIconLoader
  495.  * Load a small icon.
  496.  */
  497. KDECORE_EXPORT QPixmap SmallIcon(const QString& name, KInstance *instance);
  498.  
  499. /**
  500.  * \relates KIconLoader
  501.  * Load a small icon, and apply the necessary effects to get an IconSet.
  502.  */
  503. KDECORE_EXPORT QIconSet SmallIconSet(const QString& name, int size=0,
  504.             KInstance *instance=KGlobal::instance());
  505.  
  506. /**
  507.  * \relates KIconLoader
  508.  * Load a main toolbar icon.
  509.  */
  510. KDECORE_EXPORT QPixmap MainBarIcon(const QString& name, int size=0,
  511.             int state=KIcon::DefaultState,
  512.             KInstance *instance=KGlobal::instance());
  513.  
  514. /**
  515.  * \relates KIconLoader
  516.  * Load a main toolbar icon.
  517.  */
  518. KDECORE_EXPORT QPixmap MainBarIcon(const QString& name, KInstance *instance);
  519.  
  520. /**
  521.  * \relates KIconLoader
  522.  * Load a main toolbar icon, and apply the effects to get an IconSet.
  523.  */
  524. KDECORE_EXPORT QIconSet MainBarIconSet(const QString& name, int size=0,
  525.             KInstance *instance=KGlobal::instance());
  526.  
  527. /**
  528.  * \relates KIconLoader
  529.  * Load a user icon. User icons are searched in $appdir/pics.
  530.  */
  531. KDECORE_EXPORT QPixmap UserIcon(const QString& name, int state=KIcon::DefaultState,
  532.     KInstance *instance=KGlobal::instance());
  533.  
  534. /**
  535.  * \relates KIconLoader
  536.  * Load a user icon. User icons are searched in $appdir/pics.
  537.  */
  538. KDECORE_EXPORT QPixmap UserIcon(const QString& name, KInstance *instance);
  539.  
  540. /**
  541.  * \relates KIconLoader
  542.  * Load a user icon, and apply the effects to get an IconSet.
  543.  */
  544. KDECORE_EXPORT QIconSet UserIconSet(const QString& name,
  545.     KInstance *instance=KGlobal::instance());
  546.  
  547. /**
  548.  * \relates KIconLoader
  549.  * Returns the current icon size for a specific group.
  550.  */
  551. KDECORE_EXPORT int IconSize(KIcon::Group group, KInstance *instance=KGlobal::instance());
  552.  
  553. #endif // __KIconLoader_h_Included__
  554.